The support of this endpoint at the XS2A interface is mandatory. A TPP may execute transactions according to this use case to receive the right to execute further transactions according to the other use cases of the account information service. Subject to consent of the PSU, the TPP can obtain the following rights for transactions (of the account information service):
-
Get the list of reachable accounts of the PSU once;
-
Get the balances for a list of accounts once or multiple times;
-
Get payment transaction information for a list of accounts once or multiple times.
TPP data from certificate in request is compared in CMS with TPP data in Consent:
-
Account data should be requested by the same TPP which was given a Consent (TPP Reg_Num = tpp_id). In case when validation is unsuccessful, XS2A sends the response with HTTP code 400 CONSENT_UNKNOWN;
-
First check should be for consent access, and then for expiration;
-
The consent is considered ready to be used by the TPP to access the AIS service when the status is VALID. A consent with RECEIVED status does not have an access token yet. If TPP wants to get account details, transactions and balances with consent which status is Received, XS2A sends the response with HTTP code 401 CONSENT_INVALID;
-
In case of usage non-existent consent-id XS2A sends response with HTTP code 403 CONSENT_UNKNOWN.
The XS2A supports four different consent models:
Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request.
-
All permitted "access" attributes ("accounts", "balances" and "transactions") used in this message shall carry a non-empty array of account references, indicating the accounts where the type of access is requested.
|
Note
|
that a "transactions" or "balances" access right also gives access to the generic /accounts endpoints, i.e. is implicitly supporting also the "accounts" access. |
Consent on Dedicated Accounts affects on response body for all account endpoints:
-
Get consent request;
-
Read account list;
-
Read account details;
-
Read balance;
-
Read transaction list;
-
Read transaction details;
-
Read card accounts list;
-
Read card account details;
-
Read card account balance;
-
Read card account transaction list;
-
Read list of trusted benefeciaries;
-
Read all identifiers of single card;
-
Read detailed information of single card;
-
Read balance of single card;
-
Read transaction list of single card.
When this Consent Request is a request where the “recurringIndicator” equals true, and if it exists already a former consent for recurring access on account information for the addressed PSU and potentially addressed corporate identification submitted by this TPP, then the former consent automatically expires as soon as the new consent request is authorised by the PSU.
There are no expiration side effects foreseen for Consent Requests where the “recurringIndicator” equals false.
This function implies a consent resource at the ASPSP to return a list of all available accounts, resp. all available accounts with its balances.
The ability to create Consent on Account List of Available Accounts depends on successful validation:
-
The attribute in the ASPSP-Profile "availableAccountsConsentSupported" should be set to "TRUE". If Consent on Account List of Available Accounts is not supported in Profile - respond with 400 SERVICE_INVALID;
-
The consent should only contains the "availableAccounts" or “availableAccountsWithBalance” sub attribute within the "access" attribute with value "allAccounts";
-
All possible content of "accounts", "balances", "transactions" fields is ignored if call contains attribute "availableAccounts" or “availableAccountsWithBalance”;
-
Applying one or two-factor authorisation depends on the value of the parameter in ASPSP-Profile "scaByOneTimeAvailableAccountsConsentRequired" (true (by default), false);
-
When in profile parameter “scaByOneTimeAvailableAccountsConsentRequired”=false, request contains reccuringIndicator=false and in SPI Response "multilevelSca"=true, then multilevel flag is ignored and Consent become "Valid" after execution one-factor authorisation (login and password) by one PSU.
| Attribute | Value | Authorisation | Consent | |
|---|---|---|---|---|
Account Access |
availableAccounts OR availableAccountsWithBalance |
allAccounts |
one-factor authorisation (PSU-ID and password) |
Consent on Account List of Available Accounts |
ASPSP Profile |
availableAccountsConsentSupported |
TRUE |
||
scaByOneTimeAvailableAccountsConsentRequired |
FALSE |
|||
Account Access |
availableAccounts OR availableAccountsWithBalance |
allAccounts |
two-factor authorisation(PSU-ID and password + TAN) |
|
ASPSP Profile |
availableAccountsConsentSupported |
TRUE |
||
scaByOneTimeAvailableAccountsConsentRequired |
TRUE |
This function implies a consent without indication of Accounts. The ASPSP will then agree bilaterally directly with the PSU on which accounts the requested access consent should be supported.
During authorisation in Online-Banking PSU chooses type of consent and accesses (it may be Dedicated Account Consent, Global Consent, All Available Accounts Consent or All Available Accounts With Balances Consent) and Online-Banking stored them through the endpoint PUT /psu-api/v1/ais/consent/{consent-id}/save-access.
When TPP requests Get Consent with this consent-id, xs2a should respond with accesses written by Online-Banking in CMS during authorisation.
When TPP requests Read Account Data with this consent-id, xs2a should respond according to authorised accesses:
-
Dedicated Account Consent;
-
Global Consent;
-
All Available Accounts Consent or All Available Accounts With Balances Consent.
The ability to create Bank Offered Consent depends on successful validation:
-
The attribute in ASPSP-Profile "bankOfferedConsentSupported" should be set to "TRUE". If Bank Offered consent is not supported in Profile - respond with 400 SERVICE_INVALID;
-
The call contains the "accounts", "balances" and/or "transactions" sub attribute within the "access" attribute all with an empty array;
-
For this function the Embedded SCA Approach is not supported.
This function implies a consent on all available accounts of the PSU on all PSD2 related account information services (meaning access to all account endpoints including balances and transactions). Response for Read Account Data request, with Global Consent access, contains links for related balances and transactions. Global consent can be recurring and one-off.
The ability to create Global Consent depends on successful validation:
-
The attribute in ASPSP-Profile "globalConsentSupported" should be set to "TRUE". If Global consent is not supported in Profile - respond with 400 SERVICE_INVALID;
-
The call contains the "allPsd2" sub attribute within the "access" attribute with the value "allAccounts";
-
All possible content of "accounts", "balances", "transactions", "availableAccounts" or “availableAccountsWithBalance” fields is ignored if call contains attribute "allPsd2";
-
Applying one or two-factor authorisation depends on the value of the parameter in ASPSP-Profile "scaByOneTimeGlobalConsentRequired" (true (by default), false).
| Attribute | Value | Authorisation | Consent | |
|---|---|---|---|---|
Account Access |
allPsd2 |
allAccounts |
one-factor authorisation (PSU-ID and password) |
Global Consent |
ASPSP Profile |
globalConsentSupported |
TRUE |
||
scaByOneTimeGlobalConsentRequired |
FALSE |
|||
Account Access |
allPsd2 |
allAccounts |
two-factor authorisation(PSU-ID and password + TAN) |
|
ASPSP Profile |
globalConsentSupported |
TRUE |
||
scaByOneTimeGlobalConsentRequired |
TRUE |
All requests to the CMS concerning any consentID should be validated for mandatory field "validUntil". Field "validUntil" is adjusted for Consent in CMS according to parameter in ASPSP-Profile "maxConsentValidityDays":
-
if parameter "maxConsentValidityDays" = 0 or empty, then the maximum lifetime of Consent is infinity. Therefore no adjustment should be applied;
-
if parameter "maxConsentValidityDays" > 0, then the limit of a maximum lifetime of Consent is set in days and “validUntil” should be adjusted and stored in CMS with new value. For example, date of Consent request is 2019-03-01, “validUntil” is “9999-12-31" and "maxConsentValidityDays"=10, then adjusted value of “validUntil” should be 2019-03-10. And TPP will get new adjusted value by Get consent request;
-
if parameter "maxConsentValidityDays" > 0 and “validUntil” contains date far than it is allowed by bank, then there should be adjustment to the date according "maxConsentValidityDays". For example, date of Consent request creation is 2019-03-01, “validUntil” is “2019-04-20" and "maxConsentValidityDays"=10, then adjusted value of “validUntil” should be 2019-03-10. And TPP will get new adjusted value by Get consent request;
-
if parameter "maxConsentValidityDays" > 0 and “validUntil” contains date less than it could be allowed by bank, then no adjustment should be applied. For example, date of Consent request creation is 2019-03-01, “validUntil” is “2019-03-10" and "maxConsentValidityDays"=15, then adjusted value of “validUntil” should be 2019-03-10. And TPP will get "validUntil” =2019-03-10 by Get consent request;
-
If the date of "validUntil" is in the past, then XS2A sends the response with HTTP code 401 CONSENT_EXPIRED;
-
In case TPP tries to initiate new authorisation for expired consent, XS2A sends the response with HTTP code 403 CONSENT_EXPIRED.
Value frequencyPerDay is adjusted according to profile setting “accountAccessFrequencyPerDay” and cannot be more than it is set in the ASPSP-Profile.
Attribute "accountAccessFrequencyPerDay" in the ASPSP-Profile indicates the requested maximum frequency for an access without PSU involvement per day. For a one-off access, this attribute is set to "1"."
Number of TPP accesses is counted by every endpoint:
-
/accounts;
-
/accounts/account-id per account-id;
-
/accounts/account-id/transactions per account-id;
-
/accounts/account-id/balances per account-id;
-
/accounts/account-id/transactions/transaction-id per account-id, transaction-id, per bookingStatus if applicable.
Access to the Read Transactions endpoint is addressed several times with different values for the bookingStatus as query parameter then this is counted as one access.
The recognition of several booking statuses is needed since e.g. standing orders are only retrievable with a dedicated query parameter. This enables the TPP to retrieve e.g. the booked transactions as well as standing orders (information transactions) under the same PSU consent.
If the amount of accesses for any of these endpoints is exceeded - HTTP error 429 ACCESS_EXCEEDED is returned. All other endpoints are still accessible until their amount is not exceeded.
-
When any GET Account Data Requests contain filled parameter PSU-IP-Address, then frequencyPerDay isn’t counted for this request with recurring consent.
-
For one-off consent PSU-IP-Address is ignored and frequencyPerDay is counted.
The status of the consent (the data element "consentStatus")resource is changing during the initiation process. In difference to the payment initiation process, there are only SCA checks on the consent resource and no feedback loop with the ASPSP backend.
Status settlement:
-
While creating consent, in case of existing old unauthorised recurring consent (status "received") for one TPP and one PSU - its consent status becomes "rejected", as soon as new recurring one becomes authorised (consent status set to VALID);
-
While creating consent, in case of existing old recurring authorised consent for one TPP and one PSU - its consent status becomes "Terminated_by_TPP" as soon as new recurring consent becomes authorised (consent status set to VALID);
-
Consent without successful authorisation expire after a certain period. Consent Status becomes "rejected" and Sca Status for consent authorisation becomes "failed".
Consent Statuses which are defined as Finalised:
-
Rejected (The consent data is rejected e.g. since no successful authorisation takes place);
-
RevokedByPSU (The consent has been revoked by the PSU);
-
Expired (The consent has been expired (e.g. after 90 days);
-
TerminatedByTpp (The corresponding TPP has terminated the consent by applying the DELETE method to the consent resource).
After setting finalised status for consent:
-
status isn’t allowed to be changed in CMS any more;
-
new authorisation sub-resource can’t be created.
In case PSU decides to close an account in the bank - ASPSP enables to revoke all AIS and PIIS consents of account in one step. It can be performed via endpoint in the CMS-PSU-API.
Field lastActionDate - is containing the date of the last action on the consent object either through the XS2A interface or the PSU/ASPSP interface having an impact on the status:
-
When consent is created and gets status "Received" - lastActionDate contains date of consent creation.
-
When consent status is changed - lastActionDate also is updated with new date.
XS2A supports card accounts service with endpoints described below:
-
Read list of card accounts (
GET /v1/card-accounts) -
Read card account balances (
GET /v1/card-accounts/{account-id}/balances) -
Read card account’s transaction list (
GET /v1/card-accounts/{account-id}/transactions) -
Read details of a card account (
GET /v1/card-accounts/{account-id})
To use card account interface, one should add parameter to ASPSP profile in supportedAccountReferenceFields field (MASKED_PAN or/and PAN).
For providing access to card accounts standard AIS consent should be used.
To use Single Card Account interface, ASPSP profile should contain parameter supportedAccountReferenceFields = MASKED_PAN or/and PAN.
For providing access to single card account standard AIS consent should be used.
Account Owner Name Service The following rules and requirements for the support of this service apply:
-
An ASPSP may deliver the account owner service without any extension to the consent model as defined in [XS2A-IG].
-
An ASPSP may require an explicit consent by the PSU to deliver the account owner name service.
ASPSP may decide whether to support additional account information or not, by setting the corresponding value for parameter in the ASPSP-Profile:
-
accountOwnerInformationSupported (boolean, default value is FALSE).
If additional account information is supported by ASPSP, then after authorisation of consent ASPSP will indicate additional account information in Account Details or empty array in Account Details (if consent right to have additional info is not confirmed for this PSU).
Optional field "additionalInformation" of type "Additional Information Access" in the Consent Request:
-
is asking for additional information as added within this structured object. In case of ASPSP does not support Account Owner Name Service (accountOwnerInformationSupported = FALSE) the ASPSP ignores the corresponding entries. Consent will be created. In this case it will not be part of the consent model which is generated through the call where this object is contained.
-
value of this parameter can be array or empty:
-
The usage of this data element requires at least one of the entries "accounts", "transactions" or "balances" also to be contained in the object.
-
If the array is empty, also the arrays for accounts, balances or transactions shall be empty if used. If the array is empty in the request, the TPP is asking for the account owner name of all accessible accounts.
-
In Consent Request body fields "availableAccounts", "availableAccountsWithBalance" and "allPsd2" may have additional value "allAccountsWithOwnerName". So if any of these fields are present in consent request and ASPSP-Profile contains accountOwnerInformationSupported=true, new values are stored in consent and passed to SPI together with consent object.
On SPI Level there is new SpiAdditionalInformationAccess field In SpiAccountConsent object in SpiAccountAccess block which represents TPP desire
to retrieve additional information (ownerName) about PSU by it’s account reference.
This information ASPSP can provide through ownerName field in SpiAccountDetails object, during invoking requestAccountList or requestAccountDetailForAccount methods in AccountSpi.
Get Consent Request returns created Consent.
ASPSP may decide whether to support additional account information (Trusted Beneficiaries) or not, by setting the corresponding value for parameter in the ASPSP-Profile:
-
trustedBeneficiariesSupported (boolean, default value is FALSE).
If the ASPSP is not supporting the related consent extension (trustedBeneficiariesSupported=FALSE), then the ASPSP ignores the corresponding entries in consent body. In this case it will not be part of the consent model which is generated through the call where this object is contained. And attribute "trustedBeneficiaries" won’t be stored and won’t be present in Get Consent Response.
Permission for receiving List of Trusted Beneficiaries can be covered through:
-
Detailed Consent Model with an additionalInformation access attribute with "trustedBeneficiaries" entry. If detailed accounts are referenced, it is required in addition that any account addressed within the additionalInformation attribute is also addressed by at least one of the attributes "accounts", "transactions" or "balances".
-
Global Consent Model always covers the consent on trusted beneficiary lists, with allPSD2 access attribute with entries "allAccounts/allAccountsWithOwnerName".
-
Consent on Account List of Available Accounts will NOT give access to an overview of the list of beneficiaries.
For Bank-offered consent there is a possibility to update consent from Online-banking (In cms-psu-api) with additionalInformation with trustedBeneficiaries.
aspspAccountId - This field is a specific unique identifier for bank accounts used in payments, AIS, and PIIS consents (known to bank and given by bank) instead of IBAN and to give all consents for account by this identifier.
Parameter:
-
sets as Optional in Account Reference;
-
can be provided in response to SPI initiatePayment or initiateConsent request;
-
for PIIS aspspAccountId can be provided on creation of PIIS consent on endpoint POST /aspsp-api/v1/piis/consents as a part of account data;
-
can be used as search criteria on export endpoints in CMS then.
ASPSP can add aspspAccountId to AIS, PIIS consent while:
-
create consent request is received, or
-
get account list request is received.